<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Configuring Navigation Rules - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level3"><a href="girch.html">Using Annotations to Configure Managed Beans</a></p>
<p class="toc level4"><a href="girch.html#gircr">Using Managed Bean Scopes</a></p>
<p class="toc level5"><a href="girch.html#girep">Eager Application-scoped Beans</a></p>
<p class="toc level3 tocsp"><a href="bnawp.html">Application Configuration Resource File</a></p>
<p class="toc level4"><a href="bnawp.html#giqck">Ordering of Application Configuration Resource Files</a></p>
<p class="toc level3 tocsp"><a href="bnawq.html">Configuring Beans</a></p>
<p class="toc level4"><a href="bnawq.html#bnawr">Using the <tt>managed-bean</tt> Element</a></p>
<p class="toc level4"><a href="bnawq.html#bnaws">Initializing Properties Using the <tt>managed-property</tt> Element</a></p>
<p class="toc level5"><a href="bnawq.html#bnawu">Referencing a Java <tt>Enum</tt> Type</a></p>
<p class="toc level5"><a href="bnawq.html#bnawv">Referencing an Initialization Parameter</a></p>
<p class="toc level5"><a href="bnawq.html#bnaww">Initializing Map Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawx">Initializing Array and List Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawy">Initializing Managed Bean Properties</a></p>
<p class="toc level4 tocsp"><a href="bnawq.html#bnaxa">Initializing Maps and Lists</a></p>
<p class="toc level3 tocsp"><a href="bnaxb.html">Registering Custom Error Messages</a></p>
<p class="toc level4"><a href="bnaxb.html#gkuhg">Using <tt>FacesMessage</tt> to Create a Message</a></p>
<p class="toc level4"><a href="bnaxb.html#bnass">Referencing Error Messages</a></p>
<p class="toc level3 tocsp"><a href="bnaxc.html">Registering Custom Localized Static Text</a></p>
<p class="toc level3"><a href="gireb.html">Using Default Validators</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Configuring Navigation Rules</a></p>
<p class="toc level4"><a href="#giqwk">Implicit Navigation Rules</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnaxj.html">Basic Requirements of a JavaServer Faces Application</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxk">Configuring an Application With a Web Deployment Descriptor</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxl">Identifying the Servlet for Lifecycle Processing</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxm">Specifying a Path to an Application Configuration Resource File</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxn">Specifying Where State Is Saved</a></p>
<p class="toc level4 tocsp"><a href="bnaxj.html#giqxl">Configuring Project Stage</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxt">Including the Classes, Pages, and Other Resources</a></p>
<p class="toc level2 tocsp"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gireb.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnaxj.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnaxf"></a><h2>Configuring Navigation Rules</h2>
<a name="indexterm-800"></a><a name="indexterm-801"></a><a name="indexterm-802"></a><p>Navigation between different pages of a JavaServer Faces application, such as choosing the
next page to be displayed after a button or hyperlink component is clicked,
is defined by a set of rules. Navigation rules can be implicit, or
they can be explicitly defined in the application configuration resource file. For more
information on implicit navigation rules, see <a href="#giqwk">Implicit Navigation Rules</a>.</p>

<p>Each navigation rule specifies how to navigate from one page to another page
or a set of other pages. The JavaServer Faces implementation chooses the proper
navigation rule according to which page is currently displayed.</p>

<p>After the proper navigation rule is selected, the choice of which page to
access next from the current page depends on two factors:</p>


<ul><li><p><a name="indexterm-803"></a>The action method that was invoked when the component was clicked</p>

</li>
<li><p><a name="indexterm-804"></a>The logical outcome that is referenced by the component&rsquo;s tag or was returned from the action method</p>

</li></ul>
<p>The outcome can be anything that the developer chooses, but <a href="#bnaxg">Table&nbsp;11-3</a> lists
some outcomes commonly used in web applications.</p>

<a name="bnaxg"></a><p class="caption">Table&nbsp;11-3 Common Outcome Strings</p><table><col width="16%"><col width="83%"><tr><th align="left" valign="top" scope="column"><p>Outcome</p>

</th>
<th align="left" valign="top" scope="column"><p>What It Means</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>success</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Everything worked. Go on to
the next page.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>failure</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Something is wrong. Go on to an error page.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>login</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The user
needs to log in first. Go on to the login page.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>no results</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>The search
did not find anything. Go to the search page again.</p>

</td>
</tr>
</table><p>Usually, the action method performs some processing on the form data of the
current page. For example, the method might check whether the user name and
password entered in the form match the user name and password on file.
If they match, the method returns the outcome <tt>success</tt>. Otherwise, it returns the
outcome <tt>failure</tt>. As this example demonstrates, both the method used to process the
action and the outcome returned are necessary to determine the proper page to
access.</p>

<p>Here is a navigation rule that could be used with the example
just described:</p>

<pre>&lt;navigation-rule>
    &lt;from-view-id>/login.xhtml&lt;/from-view-id>
    &lt;navigation-case>
        &lt;from-action>#{LoginForm.login}&lt;/from-action>
        &lt;from-outcome>success&lt;/from-outcome>
        &lt;to-view-id>/storefront.xhtml&lt;/to-view-id>
    &lt;/navigation-case>
    &lt;navigation-case>
        &lt;from-action>#{LoginForm.logon}&lt;/from-action>
        &lt;from-outcome>failure&lt;/from-outcome>
        &lt;to-view-id>/logon.xhtml&lt;/to-view-id>
    &lt;/navigation-case>
&lt;/navigation-rule></pre><p><a name="indexterm-805"></a>This navigation rule defines the possible ways to navigate from <tt>login.xhtml</tt>. Each <tt>navigation-case</tt> element
defines one possible navigation path from <tt>login.xhtml</tt>. The first <tt>navigation-case</tt> says that if <tt>LoginForm.login</tt>
returns an outcome of <tt>success</tt>, then <tt>storefront.xhtml</tt> will be accessed. The second <tt>navigation-case</tt>
says that <tt>login.xhtml</tt> will be re-rendered if <tt>LoginForm.login</tt> returns <tt>failure</tt>.</p>

<p><a name="indexterm-806"></a><a name="indexterm-807"></a>The configuration of an application&rsquo;s page flow consists of a set of navigation
rules. Each rule is defined by the <tt>navigation-rule</tt> element in the <tt>faces-config.xml</tt>
file.</p>

<p><a name="indexterm-808"></a><a name="indexterm-809"></a>Each <tt>navigation-rule</tt> element corresponds to one component tree identifier defined by the optional
<tt>from-view-id</tt> element. This means that each rule defines all the possible ways to
navigate from one particular page in the application. If there is no <tt>from-view-id</tt>
element, the navigation rules defined in the <tt>navigation-rule</tt> element apply to all the pages
in the application. The <tt>from-view-id</tt> element also allows wildcard matching patterns. For example,
this <tt>from-view-id</tt> element says that the navigation rule applies to all the pages
in the <tt>books</tt> directory:</p>

<pre>&lt;from-view-id>/books/*&lt;/from-view-id></pre><p><a name="indexterm-810"></a>A <tt>navigation-rule</tt> element can contain zero or more <tt>navigation-case</tt> elements. The <tt>navigation-case</tt> element
defines a set of matching criteria. When these criteria are satisfied, the application
will navigate to the page defined by the <tt>to-view-id</tt> element contained in the
same <tt>navigation-case</tt> element.</p>

<p><a name="indexterm-811"></a>The navigation criteria are defined by optional <tt>from-outcome</tt> and <tt>from-action</tt> elements. The <tt>from-outcome</tt> element
defines a logical outcome, such as <tt>success</tt>. The <tt>from-action</tt> element uses a method expression
to refer to an action method that returns a <tt>String</tt>, which is
the logical outcome. The method performs some logic to determine the outcome and
returns the outcome.</p>

<p><a name="indexterm-812"></a><a name="indexterm-813"></a>The <tt>navigation-case</tt> elements are checked against the outcome and the method expression in
this order:</p>


<ul><li><p>Cases specifying both a <tt>from-outcome</tt> value and a <tt>from-action</tt> value. Both of these elements can be used if the action method returns different outcomes depending on the result of the processing it performs.</p>

</li>
<li><p>Cases specifying only a <tt>from-outcome</tt> value. The <tt>from-outcome</tt> element must match either the outcome defined by the <tt>action</tt> attribute of the <tt>UICommand</tt> component or the outcome returned by the method referred to by the <tt>UICommand</tt> component.</p>

</li>
<li><p>Cases specifying only a <tt>from-action</tt> value. This value must match the <tt>action</tt> expression specified by the component tag.</p>

</li></ul>
<p>When any of these cases is matched, the component tree defined by
the <tt>to-view-id</tt> element will be selected for rendering.</p>

<p>Using NetBeans IDE, you can configure a navigation rule by doing the following:</p>


<ol><li><p>After opening your project in NetBeans IDE, expand the project node in the Projects pane.</p>

</li>
<li><p>Expand the Web Pages and WEB-INF nodes of the project node.</p>

</li>
<li><p>Double-click <tt>faces-config.xml</tt>.</p>

</li>
<li><p>After <tt>faces-config.xml</tt> opens in the editor pane, right-click in the editor pane.</p>

</li>
<li><p>From the Insert menu, choose Navigation Rule.</p>

</li>
<li><p>In the Add Navigation Rule dialog:</p>


<ol style="list-style-type: lower-alpha"><li><p>Enter or browse for the page that represents the starting view for this navigation rule.</p>

</li>
<li><p>Click Add.</p>

</li></ol>
</li>
<li><p>Right-click again in the editor pane.</p>

</li>
<li><p>From the Insert menu, choose Navigation Case.</p>

</li>
<li><p>In the Add Navigation Case dialog box:</p>


<ol style="list-style-type: lower-alpha"><li><p>From the From View menu, choose the page that represents the starting view for the navigation rule (from Step 6 a).</p>

</li>
<li><p>(optional) In the From Action field, type the action method invoked when the component that triggered navigation is activated.</p>

</li>
<li><p>(optional) In the From Outcome field, enter the logical outcome string that the activated component references from its <tt>action</tt> attribute.</p>

</li>
<li><p>From the To View menu, choose or browse for the page that will be opened if this navigation case is selected by the navigation system.</p>

</li>
<li><p>Click Add.</p>

</li></ol>
</li></ol>
<p><a href="bnatn.html#bnatp">Referencing a Method That Performs Navigation</a> explains how to use a component tag&rsquo;s <tt>action</tt> attribute to point to an
action method. <a href="bnavb.html#bnavc">Writing a Method to Handle Navigation</a> explains how to write an action method.</p>



<a name="giqwk"></a><h3>Implicit Navigation Rules</h3>
<p>JavaServer Faces technology supports implicit navigation rules for Facelets applications. Implicit navigation applies
when <tt>navigation-rules</tt> are not configured in the application configuration resource files.</p>

<p>When you add a component such as a <tt>commandButton</tt> in a page, and
assign another page as the value for its <tt>action</tt> property, the default navigation
handler will try to match a suitable page within the application implicitly.</p>

<pre>&lt;h:commandButton value="submit" action="response"></pre><p>In the above example, the default navigation handler will try to locate a
page named <tt>response.xhtml</tt> within the application and navigate to it.</p>


         </div>
         <div class="navigation">
             <a href="gireb.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnaxj.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

